The X-Philes (2nd Revision)

home *** CD-ROM | disk | FTP | other *** search

/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / hp48_2 / mldl-1.02 / comp.sys.handhelds_6330_000000.msg next >

Wrap

Internet Message Format | 1991-04-30 | 36KB

Path: en.ecn.purdue.edu!noose.ecn.purdue.edu!samsung!think.com!snorkelwacker.mit.edu!ai-lab!rice-chex!bson From: bson@rice-chex.ai.mit.edu (Jan Brittenson) Newsgroups: comp.sys.handhelds Subject: HP-48 MLDL Version Beta 1.02 (Manual) Keywords: hp48 internals Message-ID: <15416@life.ai.mit.edu> Date: 30 Apr 91 00:11:18 GMT Sender: news@ai.mit.edu Organization: nil Lines: 1149 This is the manual part of MLDL version 1.02. Differences from 1.01: o Breakpoints o Server mode of operation (i.e. remote control, via wire) o Key arguments (addresses, etc) o Improved manual Enjoy, O / \/ /\ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ O \ 1. MLDL 1.02, APRIL 1991 --------------------- The MLDL is a Machine Language Development Library for the HP-48SX, and as such is primarily intended for HP-48 Machine-Language Programmers familiar with the following: o The Saturn instruction set o Assembler programming o Machine code debugging o RPL internals - GC, system RPL, PMC 1. INSTALLING THE LIBRARY ---------------------- The MLDL consists of five named commands, and has been given the number 1092 decimal (hexadecimal 444). To install it, transfer the binary file to your calculator and store it in a suitable port. Turn the calculator off, then back on, and go to the directory where you wish to attach it - HOME is fine. Enter :p:1092 where `p' is the port you stored it in, then ATTACH. To remove it, go to the directory where you previously attached it, enter `:p:1092', press DUP DETACH, then PURGE. The library does not automatically attach. Installation example, assuming I/O has been properly set up: HOME 'MLDL' KGET MLDL :0:1092 STO (Turn the calculator OFF, then back ON) :0:1092 ATTACH Removal example: HOME :0:1092 ENTER DUP DETACH PURGE The display should briefly flicker as you purge the library from the port. 3. LIBRARY COMMANDS ---------------- [ABOUTMLDL] Displays version and copyright. [MLDB] Saturn ML Debugger. This description covers the MLDB local mode. It can also operate in one of two server modes: interactive or protocol, described under MLDB Server Modes below. In Local Mode, the HP-48 display and keyboard, are used to control the debugger. In Server Mode, control is maintained via the serial port, either from a dumb ASCII terminal (Interactive Mode), or a dedicated front-end (Protocol Mode). To assert that MLDB is in Local Mode when invoked, clear user flags 32 and 33: 32 33 CF CF MLDB allows you single-step ML programs, as well as examine registers and memory contents. Since it single-steps ML, it is not useful for debugging RPL code - unless you wish to follow your RPL thread on an ML level. When invoked, an argument in expected in level 1: Code object Halts before the first instruction of the code object. Both the PC and A registers are set to the address of the first instruction. XLIB The XLIB must be a code object, which becomes the argument. Binary integer Treats the binary integer as the address of a prefixed machine code routine (PMC). Halts at the first instruction of the PMC. PMCs consist of a 5-nybble pointer to the first instruction which is usually, but not always, the address of the PMC plus 5. @#3a81 (True) Any object other than @#3a81 Ignored - the debugger returns immediately. In the future, @#3a81 (True) will cause the debugger to use the next object in sequence. It will be possible to include a call to MLDB and precede it with a test to determine whether to actually debug or run free. A user flag test, for instance. 4. Local Mode MLDB uses PICT (the graphical display) to present information. Since all information will not fit on one display at once, it has been divided into 7 screens. Only one screen is active at any one time. Switching between screens is done by means of the 6 menu keys, here referred to as A-F, which correspond to screen 1 through 6 respectively, and the MTH key, which corresponds to screen 7. The sample screens 1-7 below are from the first instruction of the PMC at #59CC, and can be reasonably reproduced by: #59CC MLDB Screen 1 - General CPU State (key [A]) Mnemonic............................ |CALL.4 #0679B | Opcode.............................. | 8E4CD0 | PC, P, Carry, Hex/Dec mode, ST...... |@:059D1 P:0 CH ST:218 | A.A and C.A......................... |A:000CC C:77794 | B.A, D.A, and HST................... |B:729A9 D:00F96 HST:2 | D0 and 6 bytes @D0.................. |D0:409C1/9540A8240BC9 | D1 and 6 bytes @D1.................. |D1:77799/000000000000 | Top 3 levels of RSTK................ |RST:00000:00000:00000 | Screen 2 - Arithmetic registers (key [B]) Mnemonic............................ |CALL.4 #0679B | Opcode.............................. | 8E4CD0 | PC, P, Carry, Hex/Dec mode, ST...... |@:059D1 P:0 CH ST:218 | Register A.......................... |A:00000005444000CC | Register B.......................... |B:000000000007611E | Register C.......................... |C:000000000007792C | Register D.......................... |D:00000000000004D0 | Top 3 levels of RSTK................ |RST:00000:00000:00000 | Screen 3 - Data registers (key [C]) Mnemonic............................ |CALL.4 #0679B | Opcode.............................. | 8E4CD0 | PC, P, Carry, Hex/Dec mode, ST...... |@:059D1 P:0 CH ST:218 | Register R0......................... |R0:053385D439800040 | Register R1......................... |R1:00000005444059D1 | Register R2......................... |R2:0000000000075BC1 | Register R3......................... |R3:0000000544402E92 | Register R4......................... |R4:00015075A6375AA1 | Top 3 levels of RSTK................ |RST:00000:00000:00000 | 5. Screen 4 - Return stack (key [D]) Mnemonic............................ |CALL.4 #0679B | Opcode.............................. | 8E4CD0 | PC, P, Carry, Hex/Dec mode, ST...... |@:059D1 P:0 CH ST:218 | | | RSTK levels 0 and 4................. |RST0:00000 RST4:00000 | RSTK levels 1 and 5................. |RST1:00000 RST5:00000 | RSTK levels 2 and 6................. |RST2:00000 RST6:00000 | RSTK levels 3 and 7................. |RST3:00000 RST7:00000 | Screen 5 - Memory dump (key [E]) Locations 59A0-59AF................. |059A0:56113680913420CC| Locations 59B0-59BF................. |059B0:4E0156716FCC56FD| Locations 59C0-59CF................. |059C0:015B38D5E0101D95| Locations 59D0-59DF................. |059D0:08E4CD08E46C0101| Locations 59E0-59EF................. |059E0:D230574911191443| Locations 59F0-59FF................. |059F0:4E4A201101311456| Locations 5A00-5A0F................. |05A00:12280A50143174E7| Locations 5A10-5A1F................. |05A10:8E58D01311741431| The current location is indicated by an inverse digit. Screen 6 - ML Instruction Stream (key [F]) PC, P, Carry, Hex/Dec mode, ST...... |@:059D1 P:0 CH ST:218 | Next 7 instructions................. |#CALL.4##0679B########| | CALL.4 #06641 | | MOVE.W A,R1 | | CLR.A C | | MOVE.P1 #5,C | | CALL.3 #05B7D | | MOVE.W R1,C | The next instruction is the one displayed in reverse. Currently, it will always appear at the top. (Here somewhat crudely illustrated with the # signs.) Screen 7 - Breakpoint Table Screen (key MTH) Breakpoint #1....................... | 1:6100 +02 | Breakpoint #2....................... | 2:6104 -02 | Breakpoint #3....................... | 3:613A 00 | Breakpoints #4-#8: not used......... | 4:0000 00 | | 5:0000 00 | | 6:0000 00 | | 7:0000 00 | | 8:0000 00 | Any breakpoints at the current location are displayed in reverse. 6. The Local Mode MLDB keyboard ---------------------------- A number of keys will accept an argument, referred to as ARG. To enter ARG, press [0] (the zero key) followed by a hex integer, which will make up ARG. It is restricted to 5 hex digits (20 bits). As [0] is pressed, the bottom display line, regardless of screen currently active, becomes an ARG entry line: |ARG:00000 | This reformat remains in effect until a non-hex key is pressed, at which point that key is passed ARG. Some keys behave differently depending on whether ARG was present - [DEL], for instance, does nothing, effectively cancelling ARG. The backarrow, [<==], divides the argument by 16, in effect shifting it right one digit. The argument is always a 20-bit unsigned integer. The digits A-F are found on the menu keys. The [+/-] key negates (2's complement) the argument. Example, ARG entry: Keys Comments Bottom line following keys 0 Start entry |ARG:00000 | 5 Digit 5 |ARG:00005 | 7 Digit 7 |ARG:00057 | [<==] Shift right |ARG:00005 | 9 Digit 9 |ARG:00059 | D1 Digits D, 1 |ARG:059D1 | [+/-] Negate |ARG:FA62F | 000 Three 0s |ARG:2F000 | [<==] Shift right |ARG:02F00 | [DEL] Cancel ARG 7. Moving about is done with the arrow keys and the NXT key - notice that none of these keys actually execute the previous instruction, only the PC is affected: [up] Decrement PC by 16 (or 16*ARG) [down] Increment PC by 16 (or 16*ARG) [left] Decrement PC by 1 (or ARG) [right] Increment PC by 1 (or ARG) [NXT] Move to next instruction (or ARG instructions forward) In addition, there is a mark: [x] (Mulitplication key) Set mark to ARG, if present. Otherwise the MARK is set to the current PC. [+/-] Swaps the PC and the mark. Example, Moving About: Keys Comments Display following keys 059D1[ENTER] PC=#059D1h |@:059D1 P:0 CH ST:218 | |#CALL.4##0679B########| | CALL.4 #06641 | | MOVE.W A,R1 | | CLR.A C | | MOVE.P1 #5,C | | CALL.3 #05B7D | | MOVE.W R1,C | 04[right] PC=PC+4 |@:059D5 P:0 CH ST:218 | |#CLR.A#A##############| | CALL.4 #06641 | | MOVE.W A,R1 | | CLR.A C | | MOVE.P1 #5,C | | CALL.3 #05B7D | | MOVE.W R1,C | 059D1[ENTER] PC=#059D1 |059A0:56113680913420CC| [E] Memory dump, |059B0:4E0156716FCC56FD| screen 5 |059C0:015B38D5E0101D95| |059D0:0#E4CD08E46C0101| |059E0:D230574911191443| |059F0:4E4A201101311456| |05A00:12280A50143174E7| |05A10:8E58D01311741431| 8. [up] PC=PC-#10h |05990:3A6E80D0F40D4F01| |059A0:56113680913420CC| |059B0:4E0156716FCC56FD| |059C0:0#5B38D5E0101D95| |059D0:08E4CD08E46C0101| |059E0:D230574911191443| |059F0:4E4A201101311456| |05A00:12280A50143174E7| 059D1[ENTER] Back to #59D1h |@:059D1 P:0 CH ST:218 | [F] ML instructions |#CALL.4##679B#########| | CALL.4 #06641 | | MOVE.W A,R1 | | CLR.A C | | MOVE.P1 #5,C | | CALL.3 #05B7D | | MOVE.W R1,C | [NXT] Forward one |@:059D7 P:0 CH ST:218 | instruction |#CALL.4##06641########| | MOVE.W A,R1 | | CLR.A C | | MOVE.P1 #5,C | | CALL.3 #05B7D | | MOVE.W R1,C | | MOVE.A C,@D0 | [x] Set mark |@:059D7 P:0 CH ST:218 | 03[NXT] Forward 3 |#MOVE.P1##5,C#########| instructions | CALL.3 #05B7D | | MOVE.W R1,C | | MOVE.A C,@D0 | | MOVE.P5 #02A4E,C | | MOVE.W R0,A | | MOVE.A A,D1 | [+/-] Toggle mark, |@:059D7 P:0 CH ST:218 | PC |#CALL.4##06641########| | MOVE.W A,R1 | | CLR.A C | | MOVE.P1 #5,C | | CALL.3 #05B7D | | MOVE.W R1,C | | MOVE.A C,@D0 | The arrow keys are most useful for moving around in the memory dump, but can also be used to arbitrarily increment and decrement the PC to shift the instruction stream by single nybbles. The mark commands are useful for temporarily remembering an address. 8. There are three ways of aborting your program, and seubsequently leaving the debugger: [<==] (Delete key) Exits. [DEL] Restores system registers to the state they were in when the debugger was entered. This is useful if you would need to exit in the middle of your program and the system registers contain random data. It does nothing if ARG was supplied, in effect acting as an ARG cancellation key. [1/X] [1/X] Panic exit. If you know the machine will crash when you exit, such as could be the case if memory has been reconfigured. Resets the calculator, which causes the MLDL to become detached. Follow the procedure described in the first section of this document to reattach. Four keys are used to execute your program: [+] Single-steps one (or ARG) instruction(s), pointed to by the PC. Follows CALLs. If ARG, then also checks for breakpoints. [-] Same as [+], but does not follows CALLs; instead, the program halts when it returns from the CALL. [.] Redraws the display but otherwise does nothing. [EVAL] Continue execution, run until program completes, breakpoint is reached, or [-] CALL execution completes. 9. The MLDB maintains a breakpoint table of eight slots. Each slot consists of an address and a counter, both of which are displayed when the MTH key is pressed (see below). The address is 20 bits and the counter is eight bits. In addition, each slot holds the breakpoint instruction (a CALL instruction) to be inserted into the program when running it. Breakpoints only work in RAM, although they can be set in ROM and triggered by multi-instruction single-steps. When a breakpoint is triggered, its counter is incremented; if after the increment it is negative (80-FF), the program will continue. Setting a negative counter is therefore a way of instruction MLDB to "ignore this breakpoint N times" where N is in the range 01-7F hexadecimal. If the counter is positive, the program is halted. Positive counters indicate how many times the program has halted at a specific breakpoint. Example, Program Completion: Start with the stack display, HEX mode, in the MLDL library menu. Only the relevant lines of the stack display are included in the example below. #3244h is DROP. Keys Comments Display following keys HEX STD Set up modes 2 1 #3244 Enter two |3: 2| [ENTER] arguments for |2: 1| DROP, and the |1: # 3244h| of the DROP PMC [MLDB] Invoke MLDB on |@:03249 P:0 H ST:218 | [F] the DROP PMC |#ADD.A##5,D1##########| and choose the | INC.A D | instruction | MOVE.A @D0,A | screen | ADD.A #5,D0 | | JUMP.A @A | | MOVE.A C,B | | MOVE.1 #3,P | The DROP PMC consists of only the first 5 instructions. The JUMP @A will cause the program to reach completion. [EVAL] Allow program |1: 2| to run freely 10. Breakpoints are accessible via three keys: [MTH] Switch to breakpoint table screen. Any entry at the current PC will be displayed in reverse video. [PRG] Set breakpoint. Waits for a further key, 1-8, which specifies the breakpoint to set. ARG is the address the breakpoint is set to. If no ARG is entered, then the breakpoint is cleared (its address and counter are set to 00000 and 00, respectively). [STO] Set breakpoint counter. Waits for a further key, 1-8, which specifies the breakpoint whose counter is to be set. ARG is the new counter value. The counter is cleared if no ARG is entered. Only the low 8 bits of ARG are used. Example, Breakpoints. For an illustration on how to enter ARG, see the "ARG entry" example above. Keys Comments Display following keys 059D1[ENTER] PC=59D1 |CALL.4 #0679B | [A] Screen 1 | 8E4CD0 | |@:059D1 P:0 CH ST:218 | |A:000CC C:77794 | |B:729A9 D:00F96 HST:2 | |D0:409C1/9540A8240BC9 | |D1:77799/000000000000 | |RST:00000:00000:00000 | [MTH] Breakpoint | 1:00000 00 | table screen | 2:00000 00 | | 3:00000 00 | | 4:00000 00 | | 5:00000 00 | | 6:00000 00 | | 7:00000 00 | | 8:00000 00 | 059D1[PRG]1 Set |#1:059D1##00##########| breakpoint 1 | 2:00000 00 | at #59D1h | 3:00000 00 | | 4:00000 00 | | 5:00000 00 | | 6:00000 00 | | 7:00000 00 | | 8:00000 00 | The inverse bar in the display above indicates that the breakpoint is set at the current PC. 11. [F] Examine next |@:059D1 P:0 CH ST:218 | 7 instructions | CALL.4 #0679B | | CALL.4 #06641 | | MOVE.W A,R1 | | CLR.A C | | MOVE.P1 #5,C | | CALL.3 #05B7D | | MOVE.W R1,C | [MTH] Back to breakpoint table screen 06641[PRG]5 Set |#1:059D1##00##########| breakpoint 5 | 2:00000 00 | at #6641h | 3:00000 00 | | 4:00000 00 | | 5:06641 00 | | 6:00000 00 | | 7:00000 00 | | 8:00000 00 | 040[+] Single-step 64 | 1:059D1 00 | instructions | 2:00000 00 | | 3:00000 00 | | 4:00000 00 | |#5:06641#+01##########| | 6:00000 00 | | 7:00000 00 | | 8:00000 00 | We never really got as far as 64 instructions. Instead we ran into the breakpoint at #6641h and stopped there. The breakpoint table above tells us why we stopped, and that it is our first stop here. Setting breakpoints and single-stepping a large number of instructions is the only way to use breakpoints in ROM. [STO]5 Clear counter | 1:059D1 00 | of breakpoint 5 | 2:00000 00 | | 3:00000 00 | | 4:00000 00 | |#5:06641##00##########| | 6:00000 00 | | 7:00000 00 | | 8:00000 00 | 12. A breakpoint is a CALL.A to an entry in the MLDB. When the breakpoint is reached, control is transfered to the breakpoint trap handler in the MLDB. It finds the location of the breakpoint on the return stack (RSTK), looks it up in the breakpoint table, and proceeds as outlined above. The CALL.A instruction uses 7 nybbles of memory. Therefore, problems can arise when the program contains a sequence like this: point: brcc foo ; 3 nybbles inc.a c ; 2 nybbles foo: inc.a c ; 2 nybbles dec.a a ; 2 nybbles Picture what would happen if a breakpoint is set at `point.' It uses up 7 nybbles of memory, and thus overwrites the BRCC, subsequent INC, and the INC at `foo.' Assume another piece of the program makes a jump to `foo.' This will result in a jump into the last two nybbles of the breakpoint instruction! The program is bound to break - if we're lucky this means mysterious results - if we're unlucky, we're going down in flames (metaphorically speaking). During a [+] single-step of multiple instructions (actually, any single-step with an ARG will do), the breakpoints are never inserted into the program. Instead, each consecutive PC is matched against the breakpoint table, and if a breakpoint is set at exactly that address, the single-stepping will stop. This usage of breakpoints is entirely safe and works under all conditions. It can, of course, be used for ROM as well as RAM programs. The drawback is execution speed, although the [-] stepping variant is usually faster than the [+] variant. Graphics and other CPU-heavy applications take seemingly forever to run. There is no simple solution - you must take the 7-nybble limit into consideration when writing such programs. Insert NOPs at places where you know you will want to insert breakpoints. The [-] single-step does not follow CALLs. It leaves control to the subroutine called and lets it run freely until it returns to the caller, which is the MLDB. It then proceeds with the next instruction in sequence, the one following the CALL. Time-consuming functions like graphics routines can be placed in separately debugged and verified subroutines, and the main program calling these routines debugged with [-]. This will generally give acceptably quick response. When during [-] step single-a subroutine that is allowed to run free until it returns, encounters a breakpoint, the program halts. The return address _into_MLDB_ will be on top of the return stack. Pressing [EVAL] to continue at this point will cause the subroutine to continue running free, until it again reaches a breakpoint, or returns, at which point it returns to MLDB and continues its [-] single-step. The subroutine can also be single-stepped when it has run into a breakpoint. 13. MLDB Server Modes ----------------- User flags 32 and 33 control the MLDB mode: Server, Server, Local Interactive Protocol ------------------------------------------ 32 Clear Set Set 33 Clear Clear Set The normal mode of operation, as described in the previous sections, is Local mode. The other two modes are referred to as Server Modes, and are the Interactive Mode - commands (see Server Commands, below) are entered on a dumb ASCII terminal or emulator, with full editing (see Server Command Entry, below) - and Protocol Mode, in which the same commands are accepted as in Interactive Mode, except no prompts are printed and commands are not echoed during reception. The Protocol Mode is intended for specialized MLDL Server Front-End Software (FES) - refer to the manual of the Server FES in question for details. 14. Server Mode Commands -------------------- Commands can be entered in response to the ``*'' prompt in Interactive Mode, or whenever suitable - they will be processed sequentially - when in Protocol Mode. Generally, excessive input is ignored, as are unrecognized commands or commands with invalid arguments. Commands of up to 40 characters can be entered. = <addr> Set the PC to <addr>. <addr> is in the range 00000-FFFFF. + <offs> Add <offs> to PC. <offs> is in the range 00000-FFFFF. - <offs> Subtract <offs> from PC. <offs> is in the range 00000-FFFFF. n [<n>] Advance PC forward <n> instructions. If no <n> is supplied, the PC is advanced one instruction. s [<n>] Single-step <n> instructions. Same as the [+] key in Local Mode. If no <n> is entered, one instruction is stepped. S [<n>] Single-step <n> instrutions, but don't follow CALLs. Same as the [-] key in Local Mode. If no <n> is entered, one instruction or CALL is is stepped. c Continue free-run execution until the program completes or a breakpoint is encountered. When the program completes, ``Exit'' is printed and MLDB exits. t Terminate. Exit with current registers. T Terminate. Exit with system registers set up exactly like when MLDB was first invoked. R Reset. r Print registers. The HEX/DEC mode is printed as ``HD:0'' or ``HD:1''. A zero means that HEX mode is active, a one means that DEC mode is active. i [<n>] [<addr>] Print instructions. <n> instructions are printed, starting at <addr>. The first argument is always <n> and the second is <addr>. If no <addr> is entered, the current PC is assumed. If <n> isn't entered, one - the next - instruction is printed. <n> and <addr> are both in the range 00000-FFFFF. 15. x [<n>] [<addr>] Print memory contents. <n> words of 16 nybbles are printed, starting at <addr>, each on a separate line. The first argument is always <n> and the second is <addr>. If no <addr> is entered, the current PC is assumed. If <n> isn't entered, one - the next - word is printed. <n> and <addr> are both in the range 00000-FFFFF. z Print the return stack - the RSTK. db <n> [<addr>] Set breakpoint <n> at <addr>. If <addr> is absent, the breakpoint is cleared. <addr> is in the range 00000-FFFFF. <n> must be in the range 1-8. hb <n> [<cntr>] Set breakpoint <n> counter to <cntr>. If <cntr> is absent, the counter is set to 00. <cntr> is in the range 00-FF. <n> must be in the range 1-8. lb List breakpoints. 16. Server Command Entry -------------------- In both Interactive and Protocol Modes, input can be edited, although no echo or response can be detected in Protocol Mode. The following table may be of help when you try to locate the editing keys on your keyboard: Backspace, Delete, Erase the last character entered. or Rubout Control-W Erase the last word entered. Control-U or Erase entire line. Control-X Control-R Rewrite input. Return, Enter, or Execute command entered. Control-M 17. Exampe, An Interactive Mode Session ----------------------------------- We invoke MLDB with #3223, the address of the SWAP PMC. We pass two arguments to SWAP - 1 and 2. First, we are greeted with a header. MLDL 1.02 Copyright (c) 1991 Jan Brittenson Let's first take a look at the SWAP PMC: * i 9 MOVE.A @D1,C ADD.A #5,D1 MOVE.A @D1,A MOVE.A C,@D1 SUB.A #5,D1 MOVE.A A,@D1 MOVE.A @D0,A ADD.A #5,D0 JUMP.A @A Then the registers: * r CY:0 P:0 PC:03228 A:0000000644403223 B:0960000000074FB3 C:0000000000075FBB D:0000000000000335 R0:000000000007BCA5 R1:0000000644403228 R2:00000000000505C6 R3:0000000644400001 R4:00015074EE274F20 D0:7C1A5 D1:75FC0 ST:000 HST:2 HD:0 So stack level 1 is at 75FC0. * x 1 75fc0 75FC0:ED2A29C2A2000000 Which is object 2A2DE. * x 2 2a2de 2A2DE:3392000000000000 2A2EE:0002033920000000 Which is a real (type prefix 2933), the constant 2. Let's step a few instructions. 18. * i MOVE.A @D1,C * s * i ADD.A #5,D1 * s * i MOVE.A @D1,A * s * i MOVE.A C,@D1 * s * i SUB.A #5,D1 * s * i MOVE.A A,@D1 * s Now, what do we have left? * i 3 MOVE.A @D0,A ADD.A #5,D0 JUMP.A @A We step a goodly chunk of instructions. That way we can be sure that the program completes. * s 100 Exit We're done. The HP-48 stack now reads "2" in level 2, and "1" in level 1. 19. Some system considerations -------------------------- The debugger has been designed explicitly so that it will not alter any static system data or depend on the precise machine configuration. The only system data it modifies is the keyboard buffer, since it relies on the system to respond to the keyboard interrupt and manage the buffer. Testing has shown that interfering with this results in poor reliability. Still, there are two instructions the debugger will refuse to single-step: RESET The effect of this would be the same as ON-C. CLRB #F,ST Executing this instruction would lock up your calculator since it would disable all I/O most notably the keyboard. Apart from the aspects outlined above and some system RPL code to do argument type checking, the debugger is self-contained. 20. A word of caution ----------------- The [-] key lets you complete an entire CALL. But beware: the return stack is replaced by one that will cause the called routine to return to the debugger. Therefore the routine called cannot rely on specific return stack contents, or remove return addresses from the stack, either of which will invariably result in a system crash. Fortunately, this appears not to be standard practice in the HP-48 ROM. Despite the effort put into avoiding system collisions, the HP-48 will still remain a largely unprotected system where the debugger - or other parts of the MLDL - can still be overwritten, which may result in memory loss. Since the MLDL is stored as a library in a port, it is not susceptible to general memory allocation, such as dynamic memory allocation or system display GROB allocations. On the other hand, storing another library in the same port may cause it to move - extreme caution is therefore advisable when single-stepping PMC that alters stored port data. If you are stepping a port store block copy by means of either [+] or [-], then the MLDL may be overwritten. If you're using [-] to call a block copy routine within a similar context, then the library may have moved and the subsequent return will cause a system crash and possibly memory corruption. Single-stepping a machine code program is in no way less dangerous than allowing it to run uncontrolled. It merely gives you some control over what happens between instructions. It can even be more dangerous; hardware may break if left in certain configurations for a period of time, which may be a fraction of a second. So if you are going to single-step parts of the system ROM, you should be aware of this risk. In no way will the author or distributors of the MLDL accept any responsibility or liability for such damage, regardless of its nature and extent. The MLDL is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 21. [MLPR] Disassembles and prints ML programs. Accepts the same arguments as MLDB, except @#3a81 and #3ac0 which are not recognized. The program is printed to the current print device - IR or Serial. In case of problems, first check your PRTPAR - see pages 602-611 in your Owner's Manual Volume II. Page 611 explicitly describes the PRTPAR. Each line consists of a mnemonic preceded by the address. No opcode is included, since it normally is of low interest. Use ML1 (described below) to build your own custom disassembler. [ML1] Disassembles one ML instruction; allows you to build your own disassemblers with special-purpose user interfaces. It takes a binary integer in level one, and returns two values; in level 2 the mnemonic form preceded by the address, and in level one the address of the next instruction. Thus it is a simple task to make a number of consequtive calls to ML1. MLOPC can be used to extract the opcode as a string of hexadecimal digits. Extract The mnemonic from the string is trivial, since it will always be of the form: "xxxxx: m" where xxxxx is a five-digit address followed by a colon and a blank. The last part of the string, m, is the mnemonic. [MLOPC] Returns opcode as a string of hexadecimal digits. Expects two binary integers - the first address in level 2 and the final address plus one in level 1. Useful for creating the opcode field in a custom disassembler. Example, MLOPC: #59D1 #59D7 MLOPC --> "8E4CD0" The opcode size is limited to 255 digits. 22. MLDL COMMAND SUMMARY -------------------- |-----------------------------------------------------------------------| | | | Version Returns version and copyright strings | | | | --> "version" "copyright" | | | |-----------------------------------------------------------------------| | | | MLDB Saturn Machine Language Debugger | | | | obj --> any1 ... anyN | | | |-----------------------------------------------------------------------| | | | MLPR Print Machine Language Program | | | | obj --> obj | | | |-----------------------------------------------------------------------| | | | ML1 Single-Instruction Machine Language Disassembler | | | | #address --> "instruction" #next | | | |-----------------------------------------------------------------------| | | | MLOPC Machine Language Instruction Opcode | | | | #address1 #address2 --> "hex digits" | | | |-----------------------------------------------------------------------+ 23. MLDB LOCAL MODE KEYBOARD SUMMARY -------------------------------- Screens No ARG ARG [A] General CPU State [B] Arithmetic registers [C] Data registers [D] Return stack (RSTK) [E] Memory dump [F] Instruction stream [MTH] Breakpoint table Breakpoint table ARG entry [0] Begins ARG entry 0-9, A-F Hex digits [+/-] 2's complement [<==] Shift right one digit [DEL] Cancel Moving around [ENTER] Ignored PC=ARG [left] PC=PC-1 PC=PC-ARG [right] PC=PC+1 PC=PC+ARG [up] PC=PC-16 PC=PC-16*ARG [down] PC=PC+16 PC=PC+16*ARG [x] MARK=PC MARK=ARG [+/-] MARK <-> PC MARK <-> PC [NXT] Advance one Advance ARG instructions instruction Breakpoints (b = 1 - 8) [MTH] Breakpoint table Breakpoint table screen screen [PRG]b Clear breakpoint b Set breakpoint b at ARG [STO]b Clear breakpoint b Set breakpoint b counter counter to ARG Program execution [+] Single-step one Single-step ARG instructions instruction [-] Single-step one Single-step ARG instructions, instruction, do do not follow CALLs. not follow CALLs [EVAL] Let program run until Ignored completed, or until breakpoint 24. MLDL XLIB TABLE --------------- The command numbers are subject to change at random and without prior notice. The library number is 444 hexadecimal, which is 1092 decimal. Command Number ---------------------- Version 1092 0 MLDB 1092 1 MLPR 1092 2 ML1 1092 3 MLOPC 1092 4 O / \/ /\ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ O \ -- Jan Brittenson bson@ai.mit.edu